IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/u_man/cat3/Tk/crtselhdlr.z/crtselhdlr

Text File | 2002-10-03 | 9.1 KB | 199 lines

TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))



NNNNAAAAMMMMEEEE
     Tk_CreateSelHandler, Tk_DeleteSelHandler - arrange to handle requests for
     a selection

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>

     TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr(_t_k_w_i_n, _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _f_o_r_m_a_t)  |

     TTTTkkkk____DDDDeeeelllleeeetttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr(_t_k_w_i_n, _s_e_l_e_c_t_i_o_n, _t_a_r_g_e_t)                            |

AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
     Tk_Window          _t_k_w_i_n        (in)      Window for which _p_r_o_c will
                                               provide selection information.

     Atom               _s_e_l_e_c_t_i_o_n    (in)      The name of the selection for  |
                                               which _p_r_o_c will provide        |
                                               selection information.

     Atom               _t_a_r_g_e_t       (in)      Form in which _p_r_o_c can provide
                                               the selection (e.g. STRING or
                                               FILE_NAME).  Corresponds to
                                               _t_y_p_e arguments in sssseeeelllleeeeccccttttiiiioooonnnn
                                               commands.

     Tk_SelectionProc   *_p_r_o_c        (in)      Procedure to invoke whenever
                                               the selection is owned by _t_k_w_i_n
                                               and the selection contents are
                                               requested in the format given
                                               by _t_a_r_g_e_t.

     ClientData         _c_l_i_e_n_t_D_a_t_a   (in)      Arbitrary one-word value to
                                               pass to _p_r_o_c.

     Atom               _f_o_r_m_a_t       (in)      If the selection requestor
                                               isn't in this process, _f_o_r_m_a_t
                                               determines the representation
                                               used to transmit the selection
                                               to its requestor.


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr arranges for a particular procedure (_p_r_o_c) to be     |
     called whenever _s_e_l_e_c_t_i_o_n is owned by _t_k_w_i_n and the selection contents   |
     are requested in the form given by _t_a_r_g_e_t. _T_a_r_g_e_t should be one of the
     entries defined in the left column of Table 2 of the X Inter-Client
     Communication Conventions Manual (ICCCM) or any other form in which an
     application is willing to present the selection.  The most common form is
     STRING.






                                                                        PPPPaaaaggggeeee 1111






TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))



     _P_r_o_c should have arguments and result that match the type
     TTTTkkkk____SSSSeeeelllleeeeccccttttiiiioooonnnnPPPPrrrroooocccc:
          typedef int Tk_SelectionProc(
               ClientData _c_l_i_e_n_t_D_a_t_a,
               int _o_f_f_s_e_t,
               char *_b_u_f_f_e_r,
               int _m_a_x_B_y_t_e_s);
     The _c_l_i_e_n_t_D_a_t_a parameter to _p_r_o_c is a copy of the _c_l_i_e_n_t_D_a_t_a argument
     given to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr.  Typically, _c_l_i_e_n_t_D_a_t_a points to a data
     structure containing application-specific information that is needed to
     retrieve the selection.  _O_f_f_s_e_t specifies an offset position into the
     selection, _b_u_f_f_e_r specifies a location at which to copy information about
     the selection, and _m_a_x_B_y_t_e_s specifies the amount of space available at
     _b_u_f_f_e_r.  _P_r_o_c should place a NULL-terminated string at _b_u_f_f_e_r containing
     _m_a_x_B_y_t_e_s or fewer characters (not including the terminating NULL), and it
     should return a count of the number of non-NULL characters stored at
     _b_u_f_f_e_r.  If the selection no longer exists (e.g. it once existed but the
     user deleted the range of characters containing it), then _p_r_o_c should
     return -1.

     When transferring large selections, Tk will break them up into smaller
     pieces (typically a few thousand bytes each) for more efficient
     transmission.  It will do this by calling _p_r_o_c one or more times, using
     successively higher values of _o_f_f_s_e_t to retrieve successive portions of
     the selection.  If _p_r_o_c returns a count less than _m_a_x_B_y_t_e_s it means that
     the entire remainder of the selection has been returned.  If _p_r_o_c's
     return value is _m_a_x_B_y_t_e_s it means there may be additional information in
     the selection, so Tk must make another call to _p_r_o_c to retrieve the next
     portion.

     _P_r_o_c always returns selection information in the form of a character
     string.  However, the ICCCM allows for information to be transmitted from
     the selection owner to the selection requestor in any of several formats,
     such as a string, an array of atoms, an array of integers, etc.  The
     _f_o_r_m_a_t argument to TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr indicates what format should be
     used to transmit the selection to its requestor (see the middle column of
     Table 2 of the ICCCM for examples).  If _f_o_r_m_a_t is not STRING, then Tk
     will take the value returned by _p_r_o_c and divided it into fields separated
     by white space.  If _f_o_r_m_a_t is ATOM, then Tk will return the selection as
     an array of atoms, with each field in _p_r_o_c's result treated as the name
     of one atom.  For any other value of _f_o_r_m_a_t, Tk will return the selection
     as an array of 32-bit values where each field of _p_r_o_c's result is treated
     as a number and translated to a 32-bit value.  In any event, the _f_o_r_m_a_t
     atom is returned to the selection requestor along with the contents of
     the selection.

     If TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr is called when there already exists a handler for |
     _s_e_l_e_c_t_i_o_n and _t_a_r_g_e_t on _t_k_w_i_n, then the existing handler is replaced with|
     a new one.                                                               |






                                                                        PPPPaaaaggggeeee 2222






TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))                              TTTTkkkk____CCCCrrrreeeeaaaatttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr((((3333TTTTkkkk))))



     TTTTkkkk____DDDDeeeelllleeeetttteeeeSSSSeeeellllHHHHaaaannnnddddlllleeeerrrr removes the handler given by _t_k_w_i_n, _s_e_l_e_c_t_i_o_n, and   |
     _t_a_r_g_e_t, if such a handler exists.  If there is no such handler then it
     has no effect.


KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
     format, handler, selection, target
















































                                                                        PPPPaaaaggggeeee 3333